Skip to content

feat(ffi/objc): add __releaseNativeCounterpart to the Node-API bridge - #113

Open
NathanWalker wants to merge 1 commit into
mainfrom
feat/napi-release-native-counterpart
Open

NathanWalker wants to merge 1 commit into
mainfrom
feat/napi-release-native-counterpart

Conversation

@NathanWalker

Copy link
Copy Markdown
Contributor

Split out of #103 (part 4), renamed and aligned with Android as requested in review.

Summary

Adds the global __releaseNativeCounterpart(obj) to the Objective-C Node-API bridge, matching Android's name and behavior, so plugins can call one thing on both platforms. It replaces #103's interop.releaseNativeObject, so there's only one public name.

  • Releases the native object now instead of when the wrapper is garbage collected. Returns undefined, like Android.
  • Throws for 0 or more than 1 arguments, and for anything that isn't a native object wrapper: primitives, plain objects, class constructors, pointers, references. The messages are the ones the existing Apple ApiTests.js cases (from the old iOS runtime) expect. Android uses different wording for the same cases.
  • Releasing an already released wrapper does nothing, as on Android.
  • After release the wrapper no longer resolves to the object: its wrap and native pointer are removed (for array Proxies, on the Proxy target too), and the object's link back to the wrapper is cleared. Later native calls throw "There was no native counterpart to the JavaScript object…" instead of reaching freed memory.
  • Instances of JS-defined classes are released too, unlike fix(ffi/objc): forward off-thread method and function callbacks to the JS thread #103, which refused them. Android and the old iOS runtime release them, and the existing Apple tests ("deallocates js derived instances created with alloc().init()" / "…with new") expect that. If native code still holds such an object and calls an overridden method, the bridge creates a new wrapper, as it does after a GC today. A new test covers this.
  • Registered in nativescript_init, so both the plain Node-API runtime and engine builds that use the napi bridge get it. Typings in packages/objc-node-api/index.d.ts.

Evidence

  • MACOS_TEST_FFI_BACKEND=napi npm run test:macos: tests=719, failures=0, errors=0, skipped=12. All 8 __releaseNativeCounterpart tests run and pass (5 existing, now no longer pending, plus 3 new: use after release throws, a second release is a no-op, a JS-defined instance held by an NSMutableArray keeps working).
  • npm run test:macos (V8 bridge): tests=719, failures=0, errors=0, skipped=13. The V8 bridge doesn't define the global yet, so the release tests stay pending there.
  • Node v26 smoke test on the plain Node-API build: use of released NSMutableArray/NSObject throws, every invalid input throws, and 2000 allocate/release cycles followed by gc() finish without a crash.

Merge Danger

Door: one-way (new public API)

Blast Radius: Objective-C napi bridge, new global only. Existing code paths are unchanged.

@coderabbitai

coderabbitai Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 65a2151f-0b9a-45a6-a245-f9e3581e2ac3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Expose the global __releaseNativeCounterpart(obj) used by the Android
runtimes so plugins can release a native object eagerly with the same
call on both platforms. It is registered from nativescript_init, so both
the engine builds using the napi FFI backend and the plain Node-API
runtime get it.

Behaviour:
- exactly one argument, otherwise throws
  'Actual arguments count: "N". Expected: "1".'
- anything that is not a live native object wrapper throws
  '<value> is an object which is not a native wrapper.'
- releasing an already released wrapper is a no-op
- returns undefined

The wrapper is detached from the bridge caches, its wrap (and the wrap
of the array proxy target) and native pointer are removed so later use
throws instead of reaching freed memory, and the bridge's retain is
dropped. The unwrapped pointer is only treated as an id once objectRefs
maps it to this exact wrapper, so pointers, references and class
constructors are rejected without being dereferenced.
@NathanWalker
NathanWalker force-pushed the feat/napi-release-native-counterpart branch from ab8965e to 4592e4c Compare November 20, 2026 21:24
@NathanWalker
NathanWalker changed the base branch from android-react-native to main November 20, 2026 21:24

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant